home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Amiga News 95
/
Amiga News 95.iso
/
dpat
/
dpat60
/
dsic
/
dsic.english.doc
next >
Wrap
Text File
|
1994-04-05
|
27KB
|
762 lines
----------------
--- DSIC ---
----------------
----------------------------------------
- Rodrigo REYES 1993 -
----------------------------------------
[A Dynamic String Implementation for the C language]
0. Introduction.
----------------
This module, basically written for the C language, was made with the
goal of eliminating a lack of C : The Dynamic Implementation of strings.
Usually, with C, if you want to use strings, you need to do yourself
your own memory allocation, loading, deleting, and re-allocation etc...
In this way, we only can appreciate the strings facilities given by
the basic language with which the programmer do nothing, because all the
code is already made.
DSIC was made because of this lack.
Its only limitation is that the programmer has to define the length of
the buffer where the strings are to be put in, with no need for him to
know anything about this. But this is a High-Level language way of
programming.
This limitation can anyway be in fact a good thing, as it forces the
programmer to know exactly the needs of its program.
DSIC is written in assembly language. I perfectly know that C compilers
uses to be top-optimizing, but I really prefer assemblor for having a full
control of my code. At most, it gives a very compact file : less than
3 kb, and nearly as many functions as the GFA-Basic !!!
1. DSIC : Inside. First approach.
---------------------------------
Here is a little sommary of the public functions of DSIC, usable
through the C language.
Buffer = StringBufferInit( Buffer )
StringBufferEnd()
NewStr = NewString( String )
NewStr = StringClone( String )
StringDelete( String )
NewStr = StringAdd( String1,String2 )
NewStr = StringUnion ( String1,String2 )
NewStr = StringSpace ( Number )
StrPtr = StringTrunc ( String )
Length = StringLength ( String )
Length = StringLen ( String ) (synonym of StringLength )
Result = StringComp ( String1,String2 )
Result = StringCompNC ( String1,String2 )
Offset = StringIndex ( MasterString,SlaveString )
Offset = StringIndexNC ( MasterString,SlaveString )
StrPtr = StringUP ( String )
StrPtr = StringDown ( String )
NewStr = StringExtract ( String,Offset,Length )
NewStr = StringLeft ( String, Length )
NewStr = StringRight ( String, Length )
NewStr = StringDec ( Number )
NewStr = StringHex ( Number )
Number = StringVal ( String )
Error = LastStringError.
(nb: NewStr as result signifies that a new string is created, and NewPtr
is a pointer on that string. StrPtr signifies that the returned pointer was
ever known from the programmer).
2. How to call it.
------------------
2.1 Using DICE.
---------------
ie. I have such a program :
void main()
{ char *StringPtr;
StringBufferInit(10000); /* allocate a 10'000 bytes long buffer */
StringPtr = NewString(" Kaka Poom Poom ! ");
StringPtr = StringTrunc(StringUp(StringPtr));
/* remove spaces & turns into upper case */
StringPtr = StringUnion(StringPtr," Ploc Ploc ?");
StringBufferEnd(); /* Clean da buffer before leaving */
return(0);
}
To compile this proggy using DICE :
_______________________________________________
| CLI | | |
------------------------------------------------
| 1> DCC ProgTest.c -oProgTest -lDLIB:DSIC.o |
| |
-------------------------------------------------
(this need the DSIC.o file to be in the DLIB: drawer, and the program
saved as ProgTest.c)
That's all. Of course you can put this line at the top of your
text :
#include "DSIC.h"
DSIC.h contains all the prototypes that your compiler may need.
2.2 Using SAS-C.
----------------
Even easier, just run SASCOPT, and specify to the LINKER options you
want the file DSIC.o to be linked with your prog. And don't forget to
add at the top of your text file the include #include "DSIC.h" (and
so the DSIC.h file has to be in your include: folder).
2.3 Using another compiler.
---------------------------
I don't know, maybe is it the same.
As long as the parameters fly thru the stack, that's OK.
3. The functions.
-----------------
_______________________________________
Function : Buffer = StringBufferInit( Length )
Parameters:
INPUT: Length : A long word containing the length of the wished
buffer. In fact, the length depend on what you
want to do. If you know you will have a lot of
strings, you ought to put a biggy number.
RESULT: Buffer : Gets the address of the buffer, but it is useless
as DSIC does all the work for you. I let it cause
it may be of some use and it takes just 4 bytes of
code.
BEWARE: Always give 0 (NULL) if the buffer hadn't
been allocated (in such a case, if you use them,
the functions shouldn't crash, but just do nothing).
EXPLAINATION: This function allocate a buffer where all the
strings are dynamically treated & re-placed.
Absolutly NEEDED for any function that needs some
place in the buffer (with a new string pointer as a
result). Other functions don't need the buffer.
EXEMPLE: StringBufferInit( 20000 ); /* Allocate 20kb of
buffer*/
_______________________________________
Function : StringBufferEnd()
Parameters:
INPUT: none
RESULT: none
EXPLAINATION: Free the memory allocated via the StringBufferInit()
function. Absolutly necessary in order to clean up
the memory. If no buffer has been allocated, just
do nothing (uncrashable!).
BEWARE : Every StringBufferInit() function should
have its StringBufferEnd().
EXEMPLE: void main()
{ StringBufferInit( 200000);
...
StringBufferEnd();
} /* GOOD */
But :
main()
{ StringBufferInit( 10000);
...
StringBufferEnd();
...
StringBufferInit( 5000);
...
StringBufferEnd();
} /* IS GOOD */
and :
main()
{
StringBufferInit( 10000);
...
StringBufferInit( 5000);
...
StringBufferEnd();
StringBufferEnd();
} /* WRONG !!!! */
/* There can be only ONE buffer at
the same time !!! */
_______________________________________
Function : NewStr = NewString( String )
Parameters:
INPUT: String: A pointer on any string. Must be NULL-TERMINATED!
(All strings given by DSIC *ARE* null-terminated).
RESULT: NewStr: A pointer on a new address for this string in the
buffer.
EXPLAINATION: This function copies a given string in the buffer.
The string given is not erased. Do the same than
StringClone().
EXEMPLE: char *mystring;
mystring = NewString("This is a string!");
mystring = Newstring("and another string");
_______________________________________
Function : NewStr = StringAdd(String1,String2);
Parameters:
INPUT: String1: A pointer on a string.
String2: A pointer on another string.
RESULT: NewStr : A new pointer on a new string.
EXPLAINATION: Creates a new string containing String1 + String2.
String1 and String2 are not changed at all.
EXEMPLE: char *string;
string = StringAdd("Janet is a slut ",
"and Brad is an asshole");
/* *string points on 'Janet is a slut and Brad is an asshole'
the two given strings are not changed */
_______________________________________
Function : StrPtr = StringUnion( String1, String2)
Parameters:
INPUT: String1 = A pointer on a string.
String2 = A pointer on a string.
RESULT: StrPtr = Pointer on the new address of String1.
EXPLAINATION: Mostly the same than StringAdd(), but instead of
just creating a new string object, this function
delete the String1 in order to relocate it.
BEWARE : The old address pointed by String1 is not valid
anymore as it has been totally erased. So you
should absolutly get the new address given by this
function for String1. No changes are made on String2.
EXEMPLE: char *string1,*string2;
string1 = StringUnion("hello ","world !");
string1 = StringUnion(string1," wonderful world!");
/* and you get 'hello world! wonderful world!' in String1 */
_______________________________________
Function : NewStr = StringClone( String )
Parameters:
INPUT: String = A string pointer.
RESULT: NewStr = Another string pointer.
EXPLAINATION: Copy the string String in the buffer and returns
its pointer. I am still wondering why I have done
this function as it does exactly the same than
NewString(). Sure there is a reason... Gonna think
about it...
EXEMPLE: char *str;
str = StringClone("Why have i done this function ?");
_______________________________________
Function : NewStr = StringSpace( Number )
Parameters:
INPUT: Number = A long word with a number.
RESULT: NewStr = A new string pointer.
EXPLAINATION: Creates a new string pointer on a string containing
<Number> white spaces.
EXEMPLE: char *spacestring;
spacestring = StringSpace(25);
/* create a string with 25 white spaces */
_______________________________________
Function : StrPtr = StringTrunc( String )
Parameters:
INPUT: String = A string pointer.
RESULT: StrPtr = The new pointer for the given string.
EXPLAINATION: Eliminates white spaces at the beginning and at the
end of the string.
BEWARE : As some spaces might be eliminated at the beginning
of the string, you should get the new address of the
string, returned by this function.
As the string may be relocated, and so erased, the
string String should be in the buffer (You can use
either NewString() or StringClone() ).
EXEMPLE: char *mystring;
mystring = NewString(" Gonna dance ");
mystring = StringTrunc(mystring);
_______________________________________
Function : Length = StringLength( String )
synonym : Length = StringLen( String )
Parameters:
INPUT: String: A string pointer.
RESULT: Length: A long word containing the length of the string,in
bytes.
EXPLAINATION: Give the length of a given string.
EXEMPLE: char *str;
int size;
str = StringTrunc( NewString(" HeLlO WoRlD \n "));
size = StringLen(str);
_______________________________________
Function : void StringDelete( String )
Parameters:
INPUT: String: Any string pointer.
RESULT: None.
EXPLAINATION: Erase every byte of a string. To do it, this
function reset to 0 every byte. The buffer area
freed is now available for any other string.
EXEMPLE: char *string;
string = NewString(" Mamma mia!");
StringDelete(string); /* erase it */
_______________________________________
Function : Result = StringComp( String1, String 2)
Parameters:
INPUT: String1: a string pointer.
String2: another string pointer.
RESULT: Result: the result of the comparison.
EXPLAINATION: Compare the two given strings and give -1 (true) if
they are strictly identical, et 0 (false) if not.
This function handles upper/lower case difference.
EXEMPLE: char *string1;
int result;
string1= NewString("A cat");
result = StringComp(string1,"A dog ?");
result = StringComp("elephant","mouse");
_______________________________________
Function : Result = StringCompNC( String1, String2)
Parameters:
INPUT: String1: a string pointer.
String2: yet another string pointer.
RESULT: Result: a long word.
EXPLAINATION: The same than StringComp(), it compares two string,
but doesn't handle lower/upper case differences.
Give -1 if true (same), et 0 if false (not the same).
EXEMPLE: int result;
result = StringCompNC("a cat","A CAT");
/* returns -1 */
_______________________________________
Function : Offset = StringIndex( BigString, LittleString)
Parameters:
INPUT: BigString: a string pointer.
LittleString: a pointer on the searched string.
RESULT: Offset: A long word containing the offset of the LittleString
in the BigString.
EXPLAINATION: Returns the offset (the index) of the sub-string
LittleString in the main string BigString.
If LittleString can't be found in BigString, this
function returns -1.
This function handle the upper/lower case differences.
EXEMPLE: int offset;
offset = StringIndex("sex, Sex, Always SEX","Sex");
/* returns 5 */
_______________________________________
Function : Offset = StringIndexNC( BigString, LittleString)
Parameters:
INPUT: BigString: A string pointer.
LittleString: another string pointer.
RESULT: Offset: Index of the first occurence of LittleString.
EXPLAINATION: Just like StringIndex(), give the offset of the
first occurence of LittleString in BigString, but
makes no difference between upper and lower case.
Returns -1 if there is no occurence of LittleString
in BigString.
EXEMPLE: int offset;
offset = StringIndex("piPiRiPaO","PAO");
/* returns 6 */
_______________________________________
Function : StrPtr = StringUp( String )
or
StringUp(String)
Parameters:
INPUT: String: A string pointer.
RESULT: StrPtr: Returns the pointer as input. (StrPtr = String).
EXPLAINATION: Turns all the lower case letters of String in
upper case.
Some people may ask why is StrPtr returning exactly
the same value than String because if we give it,
it is because we know it (of course !). In fact,
it allows some strange things like :
string = StringUnion( StringUp( NewString("hello"))," world");
This exemple creates a string in the dsic buffer, then
turns this one in upper case, and then adds another
string to it.
The same pointer flies thru every function, and finally
arrives safely in 'string'.
EXEMPLE: StringUp(mystring);
astring = StringUp(NewString("a-ha!!!"));
/* turns "a-ha!!!" to "A-HA!!!" */
_______________________________________
Function : StrPtr = StringDown( String )
or
StringDown( String )
Parameters:
INPUT: String: A string pointer.
RESULT: StrPtr: the string pointer on the converted string.
EXPLAINATION: Turns every letters of the string String in lower
case. The contrary of StringUp(). It works the
same way.
EXEMPLE: char *string;
string = StringDown( StringAdd("54321"," zero!"));
_______________________________________
Function : NewStr = StringExtract( String, Offset, Length)
Parameters:
INPUT: String: a pointer on a string.
Offset: a long word that indicates the offset.
Length: a long word that indicates the length to extract.
RESULT: NewStr: a new pointer on the new created string.
EXPLAINATION: Creates a new string in the dsic buffer, containing
<Length> characters taken from the <Offset> character
of the string <String>. Equivalent of the instruction
MID$ of basic language.
NOTE: The first character of the string has offset
0, the second has offset 1, the third 2, etc...
EXEMPLE: char *string;
string = StringExtract("I love pizza",7,4);
/* makes a new string containing "pizz" */
_______________________________________
Function : NewStr = StringLeft( String, Length)
Parameters:
INPUT: String: a string pointer.
Length: a long word containing the length to extract.
RESULT: NewStr: a new pointer on a new string.
EXPLAINATION: Extract <Length> characters from the left of the
string <String> (from the beginning of the string),
and creates a new string in the dsic buffer.
EXEMPLE: char *string;
string = StringLeft("Dear mr president...",4);
/* returns a pointer on a string containing 'dear' */
_______________________________________
Function : NewStr = StringRight( String, Length )
Parameters:
INPUT: String: a string pointer.
Length: Long word.
RESULT: NewStr: a new string pointer in dsic buffer.
EXPLAINATION: Makes a new string containing <Length> characters
of the string <String> from the right (end of the
string). A new string is created, and its pointer
is returned in <NewStr>.
EXEMPLE: char *string;
string = StringRight("May the force be with U",5);
/* string points on 'ith U' */
_______________________________________
Function : NewStr = StringDec( Number )
Parameters:
INPUT: Number: any long word value.
RESULT: NewStr: a pointeur on the ascii value.
EXPLAINATION: Turns a raw value into an ascii string. A new
string is created in the buffer.
EXEMPLE: int *chain;
chain = StringDec(999);
/* chain points on '999' */
_______________________________________
Function : NewStr = StringHex( Number )
Parameters:
INPUT: Number: any long word number.
RESULT: NewStr: a new string pointer.
EXPLAINATION: Just like StringDec(), turns a raw number into
ascii displayable format, mais this one turns the
number into an hexadecimal ascii display. No prefix
if added (no '$' nor '0x'), if you want one, add it
yourself. NewStr returns a new pointer on the new
string.
EXEMPLE: char *chain;
chain = StringHex( 4556 ); /* chain contains '11cc' */
chain = StringHex( 0x123);/* chain contains '123' */
_______________________________________
Function : Number = StringVal( String )
Parameters:
INPUT: String: A string pointer.
RESULT: Number: a unsigned long word.
EXPLAINATION: Quite identical to the VAL instruction of the basic
language, this function returns the raw integer value
contained as an ascii format in the string <String>.
The value can be given in decimal format (most
common case) or hexadecimal format (with '$' at the
begining of the ascii string).
BEWARE: StringVal() ignores the first spaces (char 32)
at the begining of the ascii string, but stop scanning
if any illegal character is encountered (non-numeric
for decimal format, non-numeric and not a,b,c,d,e, or
f for hexadecimal format).
Returns -1 is no value could be found.
In hexadecimal format, letters can be either lower or
upper case.
In hexa and in decimal, only the 8 first ascii values
are handled.
Actually, does not handle negative values.
EXEMPLE: int nb;
nb = StringVal(" $1f03aj "); /* nb= 0x1f03a */
nb = StringVal(" 1345d45z "); /* nb = 1345 */
nb = StringVal(" 1234567890"); /* nb = 12345678 */
nb = StringVal(" Now is the number 10"); /* nb = -1 */
_______________________________________
Function : Error = LastStringError()
Parameters:
INPUT: none.
RESULT: Error: the error number.
EXPLAINATION: Returns the last error number encountered by
DSIC:
0 : currently no error.
1 : Buffer is not allocated.
2 : Buffer Overflow.
EXEMPLE: int ERR;
ERR = LastStringError();
_______________________________________
4. Some last few things.
------------------------
It may be a good thing to call with no stinginess the function
StringDelete(), which allows the buffer to be erased from times to
times.
NEVER forget to use StringBufferEnd() at the end of your code. This
function is really easy to use, so you have no reason to let your
computer crash because of an error in the memory list.
Be kind with your amiga, she is not a bad girl.
VERY IMPORTANT : In any case, if a new pointer is returned by a function,
a '0' (NULL) value means the relocation function failed.
It DOES arrive when the buffer is overflow, or even more
often when the buffer was not allocated first by
StringBufferInit() (if the function was not called, or if
the function failed).
This note does not concern the functions that don't need
any new string relocation ( StringUp(), StringDown(),
StringIndex(), StringVal(), ... etc...).
5. SoftWare.
------------
This module is FREEWARE. It can be used and added to any Public Domain
program, without the author's permission. The assembly source file is
also public domain. You can change it, modify anything wrong, do want you
want with it.
My only request is that if you write something funny, usely, fantastic,
or even just working, please send me a copy of your program. This is a
request, not an obligation. This request is also valid if you modify the
source code.
This module is freeware. It means that you can spread it as long as
the package contains the files:
- DSIC.english.doc : The document you are reading.
- DSIC.francais.doc: The same document in french, my native
language.
- DSIC.h : The protos file containing the DSIC functions
protos.
- DSIC.asm : The assembly source file for this module.
- DSIC.o : The module file that has to be linked with
your program.
Of course, the author takes no responsability for any machine crash,
lost of data, or anything wrong with this module.
Rodrigo REYES __ 10/1993.
You can contact me for any comment, question, answer, or
anything else :
Rodrigo REYES
20 Residence de la grande Prairie
91330 Yerres
France.
or via electronic mail at:
SparkNet 74:320/100.7
FidoNet 2:320/214.7
internet e-mail : available soon.
or even at :
Electron BBS
node #1: (+33)-1-69394630
node #2: (+33)-1-69393152
wich are both in France, Paris, Brunoy.
and just mail me as 'Rodrigo Reyes'.
OK?
